Pagos

La API de Pagos LATAM le permite iniciar pagos desde las cuentas de su empresa, hacer seguimiento del avance de cada uno hasta su conclusión y obtener el comprobante de los pagos completados.

Esta API está disponible en el entorno de sandbox, donde usted construye y valida su integración sin mover dinero real.

Casos de Uso

• Iniciar pagos a proveedores, tributos y cuentas de servicios.
• Hacer seguimiento del estado de los pagos dentro de su sistema.
• Cancelar un pago que aún no se ha completado.
• Obtener el comprobante de cada pago completado.
• Devolver un Pix recibido.

Cómo funcionan los pagos

Cada pago se crea con un único medio de pago (Pix, TED, boleto, etc.), el valor y los datos del beneficiario. Al crearse, recibe un id, que usted usa para consultarlo, cancelarlo y obtener el comprobante.

Toda creación de pago debe enviar el header X-Idempotency-Key. Si usted repite la llamada con la misma clave, por ejemplo después de una falla de red, se devuelve el mismo pago y no se duplica nada.

Recorrido de un pago

1. Consulte la cuenta y el saldo de origen, en la API de Cuentas, saldo y extracto.
2. Inicie el pago, informando el medio, el valor y los datos del beneficiario.
3. Espere la aprobación, si es necesaria. Según las reglas de la empresa, el pago queda en pending_approval hasta ser aprobado.
4. Haga seguimiento del resultado consultando el pago por el id, hasta que llegue a un estado final.
5. Obtenga el comprobante de los pagos completados.
6. Verifique en el extracto. El pago completado aparece como débito en la cuenta.

Estado del pago

La plataforma define el estado y usted nunca lo informa.

Estado	Significado
initiated	Pago creado
pending_approval	Esperando aprobación
approved	Aprobado
settled	Completado
failed	Rechazado por el medio de pago
canceled	Cancelado antes de ser procesado

Después de settled, failed o canceled, el pago no acepta nuevas modificaciones. La excepción es la devolución de un pago ya completado.

Medios de pago

Los medios difieren solo por los datos enviados en el campo rail, de acuerdo con el type elegido.

pix

Pago por Pix. La contraparte puede informarse por clave Pix (key), por el código copia y pega (emv), por la lectura del código QR o por los datos completos de la cuenta del beneficiario. El Pix es instantáneo y no se puede deshacer; el camino es la devolución.

ted

Transferencia vía TED. Exige los datos de la cuenta del beneficiario y acepta el código de finalidad de la transferencia.

bankslip

Pago de boleto. Informe la línea digitable (digitableLine) o el código de barras (barCode). El valor pagado puede diferir del impreso, por ejemplo por los intereses y la multa del emisor, por lo que el amount pertenece al pago.

darf

Pago de tributo federal (DARF). Exige los datos del contribuyente, de la renta y del período de determinación.

utilities

Pago de cuentas de servicios (agua, luz, gas, telefonía). Informe la línea digitable del convenio y, si lo desea, el segmento de la concesionaria.

pix_reversal

Devolución de un Pix recibido. Exige el originalEndToEndId del Pix original y acepta el motivo de la devolución.

local_transfer

Transferencia a una cuenta bancaria en Uruguay, sin cambio de divisas. El direccionamiento usa el código del banco y el número de cuenta.

international_transfer

Transferencia a una cuenta en un banco en el exterior. El tipo de cambio siempre se informa y la transferencia incluye el código del banco (por ejemplo, SWIFT), la división de gastos y los datos del beneficiario.

Cancelación y devolución

Mientras el pago no se haya completado, usted puede cancelarlo. Una vez completado, el valor solo vuelve por devolución, que es un nuevo pago con el medio pix_reversal.

Comprobante

Cada pago completado tiene un comprobante, con la prueba del pago en el medio utilizado, por ejemplo el identificador del Pix, el número de la TED o el protocolo del boleto. Solicitar el comprobante antes de la conclusión devuelve un error, pues el pago aún no ocurrió.

Simulando el avance en el sandbox

En el sandbox no hay un banco real confirmando las operaciones. Para simular lo que ocurriría en producción, use el endpoint POST /{companyId}/banking/primitives/_sandbox/advance, informando el resourceId del pago y el event deseado:

event	Resultado en el pago
settle	Pago completado (settled)
fail	Rechazado por el medio de pago (failed)
require_approval	Esperando aprobación (pending_approval)
approve	Aprobado (approved)
revert	Devuelto después de completado

Recursos Disponibles

Los recursos de la API de Pagos LATAM están disponibles en el API Reference.

📘 API Reference

Pagos LATAM